Skip to content

docs: remove invalid version field from skill frontmatter#16

Merged
sjnims merged 1 commit intomainfrom
docs/12-clarify-version-field
Dec 8, 2025
Merged

docs: remove invalid version field from skill frontmatter#16
sjnims merged 1 commit intomainfrom
docs/12-clarify-version-field

Conversation

@sjnims
Copy link
Copy Markdown
Owner

@sjnims sjnims commented Dec 8, 2025

Summary

  • Remove version field from all 7 skill SKILL.md frontmatter
  • Update skill-creation-workflow.md template to exclude version field

Problem

Fixes #12

The version field was present in skill frontmatter but is not a valid field according to official Claude Code documentation. Valid skill frontmatter fields are:

  • name (required)
  • description (required)
  • allowed-tools (optional)

Solution

Remove version: 0.1.0 from all skill files since it's not a recognized field. This aligns the plugin's skills with the official specification.

Alternatives Considered

  • Document as optional field: Rejected because official docs explicitly don't support it
  • Keep and ignore: Rejected because it sets a bad example for plugin developers

Changes

  • plugins/plugin-dev/skills/*/SKILL.md (7 files): Remove version: 0.1.0 line
  • plugins/plugin-dev/skills/skill-development/references/skill-creation-workflow.md: Remove version from template example

Testing

  • All modified files pass markdownlint
  • Frontmatter structure remains valid (name + description)
  • No other references to skill version field in codebase

🤖 Generated with Claude Code

The `version` field is not a valid YAML frontmatter field for skills
according to official Claude Code documentation. Valid fields are:
- name (required)
- description (required)
- allowed-tools (optional)

Removes `version: 0.1.0` from all 7 skill SKILL.md files and updates
the skill-creation-workflow.md template to exclude this field.

Fixes #12

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@claude
Copy link
Copy Markdown

claude Bot commented Dec 8, 2025

Claude finished @sjnims's task —— View job


Review Summary

Status: Approved ✅

This PR correctly removes an invalid field from skill frontmatter, improving compliance with official Claude Code documentation.


What's Good

Accurate Problem Identification

  • The version field is indeed not a valid YAML frontmatter field for skills according to official Claude Code documentation
  • Valid skill frontmatter fields are: name (required), description (required), allowed-tools (optional)

Comprehensive Coverage

  • All 7 skill SKILL.md files updated consistently
  • Template file (skill-creation-workflow.md) also updated to prevent future propagation
  • Changes are minimal and surgical (only removing the invalid line)

Clean Implementation

  • All files remain valid after removal (name + description still present)
  • No markdown linting issues detected
  • Commit message follows conventional commits format

Markdown Linting

All files pass: markdownlint ran successfully with no errors on all 8 changed files.


Additional Verification

Searched for remaining references to skill version:

  • ✅ No version: 0.1.0 lines remain in skill frontmatter
  • ✅ Found version only in plugin.json files (where it's valid for plugin metadata)
  • ✅ No other skill-related version references that need updating

Frontmatter Structure Verified:

  • ✅ All skills retain required name and description fields
  • ✅ Frontmatter remains well-formed YAML after removal

Checklist Verification

From the PR description:

  • ✅ All modified files pass markdownlint
  • ✅ Frontmatter structure remains valid (name + description)
  • ✅ No other references to skill version field in codebase

All items confirmed.


Recommendation

Merge this PR. The changes are correct, well-documented, and align with official Claude Code plugin specifications. This sets a good example for plugin developers by removing an undocumented field that could cause confusion.


@sjnims sjnims self-assigned this Dec 8, 2025
@claude claude Bot added documentation Improvements or additions to documentation component:skill Skills layer effort:small < 1 hour labels Dec 8, 2025
@sjnims sjnims merged commit 8521d81 into main Dec 8, 2025
8 checks passed
@sjnims sjnims deleted the docs/12-clarify-version-field branch December 8, 2025 00:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

component:skill Skills layer documentation Improvements or additions to documentation effort:small < 1 hour

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: clarify version field in agent-development skill

1 participant